OpenEdge Application Server:<br />Developing WebSpeed Applications Message handling

A number of WebSpeed API functions facilitate message queuing and output. They interact with a message queue that allows you to organize messages into named groups. Table 3–2 lists these functions.

Table 3–2: Message API functions
Function	Return type	Description
available-messages	LOGICAL	Returns `TRUE` if there are any messages queued for a specified group or for all groups.
get-messages	CHARACTER	Returns any messages queued for a specified group or for all groups. Optionally deletes the messages from the queue.
get-message-groups	CHARACTER	Returns a comma-separated list of groups for which there are queued messages.
output-messages	INTEGER	Outputs messages to the Web that have been queued by queue-message and returns the number of messages output. Includes options to format the output and to specify a specific group of messages or all messages.
queue-message	INTEGER	Queues a message for later output by output-messages and returns the message number in the queue. Optionally associates the message with a specified group.

The definitions for these functions reside in install-path/src/web/method/message.i.

Generating messages directly

In embedded SpeedScript and SpeedScript-generating Web objects, where the program code explicitly controls the HTML output, you can call the message API function directly. For most applications you only need to use output-messages and queue-messages. These API functions call the other message API functions.

Generating messages with a custom tag

For HTML-mapping Web objects, WebSpeed provides a custom tag () in tagmap.dat to output messages at strategic points in a mapped HTML file. Generally, you invoke the queue-message function to append a message to the message queue. If you want a certain group of messages to be output to the Web, you can insert the  tag for that group of messages at any point in the HTML file.

NAME — The name of the message group or "all" for all messages in the queue.

VALUE — The heading to appear prior to the messages output for the specified group.

Using the custom tag with no attributes defaults to TYPE="application messages" and NAME="all".

The following HTML example contains two  tags, one for messages in a CustNum group and one for messages in a CustName group. When the HTML-mapping Web object invokes the output-fields event procedure, the messages for each respective group are output in the Web page at the specified point, as shown in this code:

<FORM ACTION="custnum.w" METHOD="post"> <P> `<!--WSMSG NAME="CustNum" VALUE="Customer Number Errors" -->`<HR> Enter Customer Number: <INPUT TYPE="text" NAME="Customer_Number"> <BR> <INPUT TYPE="submit" NAME="SUBMIT"> <BR> <HR> `<!--WSMSG NAME="CustName" VALUE="Customer Name Errors" -->` Customer Name: <INPUT TYPE="text" NAME="Customer_Name"> <BR> Customer Phone: <INPUT TYPE="text" NAME="Customer_Phone">

<FORM ACTION="custnum.w" METHOD="post"> 
<P> 
<!--WSMSG NAME="CustNum" VALUE="Customer Number Errors" --> 
<HR> 
Enter Customer Number: 
<INPUT TYPE="text" NAME="Customer_Number"> <BR> 
<INPUT TYPE="submit" NAME="SUBMIT"> <BR> 
<HR> 
<!--WSMSG NAME="CustName" VALUE="Customer Name Errors" --> 
Customer Name: 
<INPUT TYPE="text" NAME="Customer_Name"> <BR> 
Customer Phone: 
<INPUT TYPE="text" NAME="Customer_Phone">

The tagmap utility procedure install-path/src/web/support/webmsg.p contains the default web.output control handler to output the HTML for this custom tag.